Feedback requested - Initial design documents templates#1
Feedback requested - Initial design documents templates#1mkhansenbot merged 9 commits intoros-navigation:masterfrom
Conversation
| @@ -0,0 +1,18 @@ | |||
| # Requirement Title | |||
| The <navigation system> should be able to <shall> <do something> | |||
There was a problem hiding this comment.
I think these angle brackets should be escaped. Markdown allows for some inline markup, so these are not being interpreted correctly by the renderer. They don't show up correctly in Visual Studio code, at least. Searching online, it seems you can use a single backslash before the opening angle bracket: \<navigation system>, for example, instead of <navigation system>.
design/README.md
Outdated
| @@ -0,0 +1,15 @@ | |||
| # ROS2 Navigation Design documenation | |||
| ## More details | ||
| - I want to be able to write or use my own collision avoidance algorithm without having to re-compile the entire stack from source | ||
| - Ideally I can just change out a node using a custom launch file | ||
| - This maps to the "Collision avoidance" use case |
There was a problem hiding this comment.
I'd suggest use case names be capitalized: "Collision avoidance" -> "Collision Avoidance"
| @@ -0,0 +1,15 @@ | |||
| # ROS2 Navigation Design documenation | |||
| This is where the ROS2 Navigation design documentation is being collected and vetted | |||
There was a problem hiding this comment.
"ROS2 Navigation" here is inconsistent with the previous README.md, which uses "ROS2 navigation"
design/README.md
Outdated
| @@ -0,0 +1,15 @@ | |||
| # ROS2 Navigation Design documenation | |||
There was a problem hiding this comment.
Inconsistent capitalization. I'd say either "ROS2 Navigation design documentation" or "ROS2 Navigation Design Documentation" Should be consistent on titles.
| - Why is this needed? | ||
| - What is the expected user interaction? | ||
| - What use case does this map to? | ||
|
|
There was a problem hiding this comment.
I suggest we add: "Are there any non-functional requirements associated with this functional requirement?"
| @@ -0,0 +1,16 @@ | |||
| # Use case Title | |||
There was a problem hiding this comment.
Inconsistent capitalization: "Use Case Title" or "Use case title"
| @@ -0,0 +1,16 @@ | |||
| # Use case Title | |||
| As a <Developer, Researcher, Technician, etc.> I want the robot to <action> so that <I, the robot, etc.> can <do something important> | |||
There was a problem hiding this comment.
As before, we should escape these angle brackets.
| ## More details | ||
| - Why is this needed? | ||
| - What is the expected user interaction? | ||
|
|
There was a problem hiding this comment.
I suggest we add: "Are there any non-functional requirements associated with this use case?"
mjeronimo
left a comment
mjeronimo
left a comment
There was a problem hiding this comment.
A couple typos, some inconsistent capitalization, and a few recommendations.
|
@mjeronimo - I made fixes & changes you suggested. Please review again. |
|
Thanks for the review help! |
|
You bet! Looking forward to getting input from the ROS community. |
…ll refactorization Signed-off-by: Jakubach <jakubach@gmail.com>
2 participants
Initial design documentation templates and examples